I am incredibly excited to announce the release of ColdBox v6.7.0 and its standalone companion libraries: CacheBox, LogBox and WireBox. This is an action packed release for all internal libraries with a big focus on performance, async programming, task scheduling and testing. With that said, let's explore this release. How do you update?

Updating ColdBox

update coldbox

# If you are using standalone libraries, then update those
update wirebox
update cachebox
update logbox

You can find our what's new document here: https://coldbox.ortusbooks.com/intro/release-history/whats-new-with-6.7.0. So let's explore the release notes.

Major Updates

Here is a listing of all the major updates and improvements in this version.

Event Caching HTTP Response Codes

Event caching has been updated to allow the caching of the set http response code from your handler code via event.setHTTPHeader() or event.renderData() . This is essential from a developer's perspective as it will respect whatever response code you respond with. This is also imperative for RESTFul services.

function data( event, rc, prc ) cache=true cacheTimeout=5{
    
    event.setHTTPHeader( statusCode = 404 );

}

WireBox Performance, Performance and More Performance

This release brings in a complete re-architecture of the creation, inspection and wiring of objects in WireBox in order to increase performance. Every single line of code was optimized and analyzed in order to bring the creation, inspection and wiring of objects to its maximum speed. This will be noted more on the creation of transient (non-persisted) objects more than in singleton objects. So if you are asking WireBox for transient objects, you will see and feel the difference.

In some of our performance testing we had about 4000 object instantiations running between 500ms-1,100 ms depending on CPU load. While with simple createObject() and no wiring, they click around 400-700 ms. Previously, we had the same instantiations clocking at 900-3,500 ms. So we can definitely see a major improvement in this area.

New ColdBox Testing Virtual App

This release sports the creation of the encapsulated virtual ColdBox App: coldbox.system.testing.VirtualApp. Previously, the only way to create virtual apps was to do it manually just like the BaseTestCase object did when doing integration testing and that's about it. In this release, we provide a clean interface for starting, restarting, checking and shutting down virtual applications that can be used for testing, proxying, etc. It also allows a faster and eager approach to starting the virtual application before your runner and tests. This will allow any ORM bridges to be respected and best of all the ability to execute anything in the framework before your runners, suites or specs. Database migrations anyone?

Test Harness

All application templates have been updated to use the new Virtual App in the tests/Application.cfc. This will allow for a virtual application to be started once your runner or specs are executed and shutdown at the end of the request. Here are the two methods in charge of doing this in the Application.cfc

public boolean function onRequestStart( targetPage ){
	// Set a high timeout for long running tests
	setting requestTimeout="9999";
	// New ColdBox Virtual Application Starter
	request.coldBoxVirtualApp = new coldbox.system.testing.VirtualApp( appMapping = "/root" );

	// If hitting the runner or specs, prep our virtual app
	if ( getBaseTemplatePath().replace( expandPath( "/tests" ), "" ).reFindNoCase( "(runner|specs)" ) ) {
		request.coldBoxVirtualApp.startup();
	}

	// ORM Reload for fresh results
	if( structKeyExists( url, "fwreinit" ) ){
		if( structKeyExists( server, "lucee" ) ){
			pagePoolClear();
		}
		// ormReload();
		request.coldBoxVirtualApp.restart();
	}

	return true;
}

public void function onRequestEnd( required targetPage ) {
	request.coldBoxVirtualApp.shutdown();
}

Your integration tests and unit tests remain the same. The only difference is that internally they all use this object to create the virtual applications.

Scheduled Tasks Exception Handling

All scheduled tasks have automatic exception handling now. Before, whenever you had exceptions and you did NOT implement any of the exception handling listeners, your code would be swallowed up and never to be seen! Now, we avoid this and log them to standard error so you can debug your code.

Also, in the previous version, if you had an exception your afterAnyTask() or the after() life cycle methods would never be called. Now they are!! Hooray!!

ColdBox Schedulers Automatic Injection

All ColdBox enabled schedulers will have the following automatic injections so you can have ease of use for leveraging objects and contexts during your task declarations and executables.

Property	Description
controller	The ColdBox running app controller
cachebox	The CacheBox reference
wirebox	The WireBox reference
log	A configured LogBox logger
coldboxVersion	The ColdBox version you are running
appMapping	The ColdBox app mapping
getJavaSystem()	Function to get access to the java system
getSystemSetting()	Retrieve a Java System property or env value by name. It looks at properties first then environment variables
getSystemProperty()	Retrieve a Java System property value by key
getEnv()	Retrieve a Java System environment value by name

All module schedulers will have the following extra automatic injections:

Property	Description
moduleMapping	The module’s mapping
modulePath	The module’s path on disk
moduleSettings	The module’s settings structure

Scheduled Tasks Start and End Dates

All scheduled tasks now support the ability to seed in the start and end dates via our DSL:

• startOn( date, time = "00:00" )
• endOn( data, time = "00:00" )

This means that you can tell the scheduler when the task will become active on a specific data and time (using the scheduler's timezone), and when the task will become disabled.

task( "restricted-task" )
  .call( () => ... )
  .everyHour()
  .startOn( "2022-01-01", "00:00" )
  .endOn( "2022-04-01" )

xTask() - Easy Disabling of Tasks

Thanks to the inspiration of TestBox where you can mark a spec or test to be skipped from execution by prefixing it with the letter x you can now do the same for any task declaration. If they are prefixed with the letter x they will be registered but disabled automatically for you.

function configure(){

	xtask( "Disabled Task" )
		.call ( function(){
			writeDump( var="Disabled", output="console" );
		})
		.every( 1, "second" );

	task( "Scope Test" )
		.call( function(){
			writeDump( var="****************************************************************************", output="console" );
			writeDump( var="Scope Test (application) -> #getThreadName()# #application.keyList()#", output="console" );
			writeDump( var="Scope Test (server) -> #getThreadName()# #server.keyList()#", output="console" );
			writeDump( var="Scope Test (cgi) -> #getThreadName()# #cgi.keyList()#", output="console" );
			writeDump( var="Scope Test (url) -> #getThreadName()# #url.keyList()#", output="console" );
			writeDump( var="Scope Test (form) -> #getThreadName()# #form.keyList()#", output="console" );
			writeDump( var="Scope Test (request) -> #getThreadName()# #request.keyList()#", output="console" );
			writeDump( var="Scope Test (variables) -> #getThreadName()# #variables.keyList()#", output="console" );
			writeDump( var="****************************************************************************", output="console" );
		} )
		.every( 60, "seconds" )
		.onFailure( function( task, exception ){
			writeDump( var='====> Scope test failed (#getThreadName()#)!! #exception.message# #exception.stacktrace.left( 500 )#', output="console" );
		} );
		
}

Scheduled Tasks Singular Time Units

Every time unit can now be used as plural or singular, so it can allow you to create beautiful scheduled task DSLs:

// Before
task( "my-task" )
	.call( () => {} )
	.every( 1, 'hours' );

// Which sounds weird when you read it. So now you can use singular

task( "my-task" )
	.call( () => {} )
	.every( 1, 'hour' );

Available Time Units

• Nanosecond(s)
• Microsecond(s)
• Millisecond(s)
• Second(s)
• Minute(s)
• Hour(s)
• Day(s)

Safe Shutdown of Executors and Schedulers

All executors and schedulers can now be shutdown more gracefully by passing a timeout argument to the async manager and automatically by the framework. This will allow the executor to shutdown and gracefully yell at it's tasks to shutdown in a default period of 30 seconds. It will wait and then try again, if not, then well, you can't directly kill anything anymore, so you will be notified so you can do harsher punishments to these tasks.

The only exception this is NOT the case in a normal ColdBox app is when a reinit happens or when integration testing is being executed. Then we revert to the previous behavior of nuking the executors and schedulers.

AsyncManager

• shutdownAllExecutors( force, timeout )
• shutdownExecutor( name, force, timeout)

The timeout ONLY works when the force argument is false. If force is true, then it's NOT gracefully shutdown. This usually happens on ColdBox reinits or integration testing.

---

Schedulers

All schedulers have a shutdownTimeout property that defaults to 30 seconds. When you configure your schedulers you can change this value to whatever you see fit.

function configure(){
    
    // Set shutdown timeout to 60 seconds
    setShutdownTimeout( 60 );

}

Executors - shutdown and wait...

All executors now have a new method: shutdownAndAwaitTermination( numeric timeout = 30 ) which is used to do just that. It places the executor in shutdown mode and waits the timeout for all the tasks to complete. If they don't complete then it issues a forced shutdown.

forAttribute() - Integrate with JS Frameworks Easily

All handlers/layouts and views get a new function called forAttribute( data )which will allow you to serialize simple or complex data so it can be used within HTML attributes. This will take care of serialize the data and encoding it correctly so it can be bound to the HTML attribute so the JavaScript framework can use it as native JSON.

This technique will allow you to bridge your CFML apps with your JS apps natively.

Async Interceptors Data

Finally in this version of ColdBox asynchronous interceptors will work with any complex data without any thread contingency or duplication. You can even use them for ORM events and it will work accordingly. So go for it, asynchronize your interception calls!

threadData = announce(
    state           = "onPageCreate", 
    data            = { page= local.page }, 
    asyncAll        = true,
    asyncPriority   = "high"
);

ORM Event Handling

This was a rough regression due to the way Hibernate is loaded by the CFML engines. We have moved to a lazy load first strategy on the entire architecture of the framework. So anything using the ColdBox proxy, like the ORM event handling, will now work in any loading situation.

Release Notes

ColdBox HMVC Core

Bug

• COLDBOX-1114 Persistance of variables failing due to null support
• COLDBOX-1110 Renderer is causing coldbox RestHandler to render convention view
• COLDBOX-1109 Exceptions in async interceptors are missing onException announcement
• COLDBOX-1105 Interception with async annotation causes InterceptorState Exception on Reinit
• COLDBOX-1104 A view not set exception is thrown when trying to execution handler ColdBox methods that are not concrete actions when they should be invalid events.
• COLDBOX-1103 Update getServerIP() so it avoids looking at the cgi scope as it can cause issues on ACF
• COLDBOX-1100 Event Caching Does Not Preserve HTTP Response Codes
• COLDBOX-1099 Regression on ColdBox v6.6.1 around usage of statusCode = 0 on relocates
• COLDBOX-1098 RequestService context creation not thread safe
• COLDBOX-1097 Missing scopes on isNull() checks
• COLDBOX-1092 RestHandler Try/Catches Break In Testbox When RunEvent() is Called
• COLDBOX-1045 Scheduled tasks have no default error handling
• COLDBOX-1043 Creating scheduled task with unrecognized timeUnit throws null pointer
• COLDBOX-1042 afterAnyTask() and task.after() don't run after failing task
• COLDBOX-1040 Error in onAnyTaskError() or after() tasks not handled and executor dies.
• COLDBOX-966 Coldbox Renderer.RenderLayout() Overwrites Event's Current View

Improvement

• COLDBOX-1124 Convert mixer util to script and utilize only the necessary mixins by deprecating older mixins
• COLDBOX-1116 Enhance EntityNotFound Exception Messages for rest handlers
• COLDBOX-1096 SES is always disabled on RequestContext until RoutingService request capture : SES is the new default for ColdBox Apps
• COLDBOX-1094 coldbox 6.5 and 6.6 break ORM event handling in cborm
• COLDBOX-1067 Scheduled Tasks: Inject module context variables to module schedulers and inject global context into global scheduler
• COLDBOX-1044 Create singular aliases for timeunits

New Feature

• COLDBOX-1123 New xTask() method in the schedulers that will automatically disable the task but still register it. Great for debugging!
• COLDBOX-1121 Log schedule task failures to console so errors are not ignored
• COLDBOX-1120 Scheduler's onShutdown() callback now receives the boolean force and numeric timeout arguments
• COLDBOX-1119 The Scheduler's shutdown method now has two arguments: boolean force, numeric timeout
• COLDBOX-1118 All schedulers have a new property: shutdownTimeout which defaults to 30 that can be used to control how long to wait for tasks to gracefully complete when shutting down.
• COLDBOX-1113 New coldobx.system.testing.VirtualApp object that can startup,restart and shutdown Virtual Testing Applications
• COLDBOX-1108 Async interceptos can now discover their announced data without duplicating it via cfthread
• COLDBOX-1107 Interception Event pools are now using synchronized linked maps to provide concurrency
• COLDBOX-1106 New super type function "forAttribute" to help us serialize simple/complex data and encoded for usage in html attributes
• COLDBOX-1101 announce onException interception from RESTHandler, when exceptions are detected
• COLDBOX-1053 Async schedulers and executors can now have a graceful shutdown and await for task termination with a configurable timeout.
• COLDBOX-1052 Scheduled tasks add start and end date/times

Task

• COLDBOX-1122 lucee async tests where being skipped due to missing engine check
• COLDBOX-1117 Remove nextRun stat from scheduled task, it was never implemented

CacheBox

Bug

• CACHEBOX-66 Cachebox concurrent store meta index not thread safe during reaping

Improvement

• CACHEBOX-82 Remove the usage of identity hash codes, they are no longer relevant and can cause contention under load

LogBox

Improvement

• LOGBOX-68 Remove the usage of identity hash codes, they are no longer relevant and can cause contention under load
• LOGBOX-65 File Appender missing text "ExtraInfo: "

WireBox

Bug

• WIREBOX-126 Inherited Metadata Usage - Singleton attribute evaluated before Scopes

Improvement

• WIREBOX-129 Massive refactor to improve object creation and injection wiring
• WIREBOX-128 Injector now caches all object contains lookups to increase performance across hierarchy lookups
• WIREBOX-127 Lazy load all constructs on the Injector to improve performance
• WIREBOX-125 Remove the usage of identity hash codes, they are no longer relevant and can cause contention under load